<?php

abstract class HttpUtility {

  /**
   * Decodes data encoded with MIME base64.
   * @param String $data The encoded data.
   * @param Boolean $strict Character from inside the base64 alphabet.
   * @return String Returns the original data or FALSE on failure.<br />
   * The returned data may be binary.
   * @link http://be.php.net/manual/en/function.base64-decode.php<br />
   * @throws BeObjectException
   */
  public static function base64Decode(String $data, Boolean $strict = null) {
    $return = $strict == null ? base64_decode($data, false) : base64_decode($data, $strict->booleanValue());

    if ($return === false) {
      throw new BeObjectException("The decoding process fails.");
    }
    return new String($return);
  }

  /**
   * Encodes data with MIME base64.
   * @param String $data The string to encode.
   * @return String The base64 encoded string.
   * @link http://be.php.net/manual/en/function.base64-encode.php<br />
   * @throws BeObjectException
   */
  public static function base64Encode(String $data) {
    $return = base64_encode($data->toString());

    if ($return === false) {
      throw new BeObjectException("The encoding process fails.");
    }
    return new String($return);
  }

  /**
   * Generate URL-encoded query string.<br />
   * Generates a URL-encoded query string from the associative (or indexed) array provided.
   * @param array $formdata May be an array or object containing properties.<br />
   * The array form may be a simple one-dimensional structure, or an array of arrays (who in turn may contain other arrays).
   * @param String $numeric_prefix If numeric indices are used in the base array and this parameter is provided, it will be prepended to the numeric index for elements in the base array only.<br />
   * This is meant to allow for legal variable names when the data is decoded by PHP or another CGI application later on.
   * @param String $arg_separator arg_separator.output is used to separate arguments, unless this parameter is specified, and is then used.
   * @return String Returns a URL-encoded string.
   * @link http://fr2.php.net/manual/en/function.http-build-query.php
   */
  public static function buildQuery(array $formdata, String $numeric_prefix = null, String $arg_separator = null) {
    return new String(http_build_query($formdata, ($numeric_prefix == null ? "" : $numeric_prefix->toString()), ($arg_separator == null ? "&amp;" : $arg_separator->toString())));
  }

  /**
   * Fetches all the headers sent by the server in response to a HTTP request.
   * @param String $url The target URL.
   * @param Boolean $format If the optional format parameter is set to non-zero, getHeaders() parses the response and sets the array's keys.
   * @return array An indexed or associative array with the headers
   * @link http://be.php.net/manual/en/function.get-headers.php<br />
   * @throws BeObjectException
   */
  public static function getHeaders(String $url, Boolean $format = null) {
    $return = get_headers($url->toString(), $format == null ? 0 : $format->booleanValue() == true ? 1 : 0);

    if ($return === false) {
      throw new BeObjectException("The request fails.");
    }
    return $return;
  }

  /**
   * Extracts all meta tag content attributes from a file and returns an array.
   * @param String $filename The path to the HTML file, as a string.<br />
   * This can be a local file or an URL.
   * @param Boolean $use_include_path Setting use_include_path to true will result in PHP trying to open the file along the standard include path as per the include_path directive.<br />
   * This is used for local files, not URLs.
   * @return array An array with all the parsed meta tags.<br />
   * The value of the name property becomes the key, the value of the content property becomes the value of the returned array, so you can easily use standard array functions to traverse it or access single values.<br />
   * Special characters in the value of the name property are substituted with '_', the rest is converted to lower case.<br />
   * If two meta tags have the same name, only the last one is returned.
   * @link http://be.php.net/manual/en/function.get-meta-tags.php
   */
  public static function getMetaTags(String $filename, Boolean $use_include_path = null) {
    return get_meta_tags($filename, $use_include_path == null ? false : $use_include_path->booleanValue());
  }

  /**
   * Parse a URL and return its components.<br />
   * This function parses a URL and returns an associative array containing any of the various components of the URL that are present.<br />
   * This function is not meant to validate the given URL, it only breaks it up into the above listed parts.<br />
   * Partial URLs are also accepted, HttpUtility::parseUrl() tries its best to parse them correctly.
   * @param String $string The URL to parse.<br />
   * Invalid characters are replaced by '_'.
   * @param Integer $component Specify one of PHP_URL_SCHEME, PHP_URL_HOST, PHP_URL_PORT, PHP_URL_USER, PHP_URL_PASS, PHP_URL_PATH, PHP_URL_QUERY or PHP_URL_FRAGMENT to retrieve just a specific URL component as a string.
   * @return mixed An associative array, whose components may be (at least one): scheme - e.g. http, host, port, user, pass, path, query - after the question mark ?, fragment - after the hashmark #.<br />
   * @link http://fr2.php.net/manual/en/function.parse-url.php
   */
  public static function parseUrl(String $string, Integer $component = null) {
    return $component == null ? array(parse_url($string, -1)) : parse_url($string, $component->integerValue());
  }

  /**
   * Decode URL-encoded strings.<br />
   * Returns a string in which the sequences with percent (%) signs followed by two hex digits have been replaced with literal characters.
   * @param String $string The URL to be decoded.
   * @return String Returns the decoded URL, as a string.
   * @link http://fr2.php.net/manual/en/function.rawurldecode.php
   */
  public static function rawUrlDecode(String $string) {
    return new String(rawurldecode($string->toString()));
  }

  /**
   * URL-encode according to RFC 1738.<br />
   * Encodes the given string according to » RFC 1738.
   * @param String $string The URL to be encoded.
   * @return String Returns a string in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits.<br />
   * This is the encoding described in » RFC 1738 for protecting literal characters from being interpreted as special URL delimiters, and for protecting URLs from being mangled by transmission media with character conversions (like some email systems).
   * @link http://fr2.php.net/manual/en/function.rawurlencode.php
   */
  public static function rawUrlEncode(String $string) {
    return new String(rawurlencode($string->toString()));
  }

  /**
   * Decodes URL-encoded string.<br />
   * Decodes any %## encoding in the given string.
   * @param String $string The string to be decoded.
   * @return String Returns the decoded string.
   * @link http://fr2.php.net/manual/en/function.urldecode.php
   */
  public static function urlDecode(String $string) {
    return new String(urldecode($string->toString()));
  }

  /**
   * URL-encodes string.<br />
   * This function is convenient when encoding a string to be used in a query part of a URL, as a convenient way to pass variables to the next page.
   * @param String $string The string to be encoded.
   * @return String Returns a string in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits and spaces encoded as plus (+) signs.<br /><br />
   * @link http://fr2.php.net/manual/en/function.urlencode.php
   */
  public static function urlEncode(String $string) {
    return new String(urlencode($string->toString()));
  }

}

?>
